From 1c555a8586950d3a4f2ff7d92a1122569b417aca Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 15:13:36 -0400 Subject: [PATCH] Consolidate all info about specifying deps into one page. I think information about specifying dependencies deserves to have its own page since this info is commonly needed and there are a LOT of different ways to specify dependencies. Previously this information was spread across multiple pages, now there's one place to go if you're looking for any of these ways, rather than checking the multiple pages this info was spread across before. --- Makefile.in | 2 +- src/doc/crates-io.md | 69 ------- src/doc/guide.md | 109 +---------- src/doc/header.html | 1 + src/doc/manifest.md | 100 +--------- src/doc/specifying-dependencies.md | 304 +++++++++++++++++++++++++++++ 6 files changed, 313 insertions(+), 272 deletions(-) create mode 100644 src/doc/specifying-dependencies.md diff --git a/Makefile.in b/Makefile.in index 96e960364..245353fed 100644 --- a/Makefile.in +++ b/Makefile.in @@ -136,7 +136,7 @@ clean: # === Documentation DOCS := index faq config guide manifest build-script pkgid-spec crates-io \ - environment-variables + environment-variables specifying-dependencies DOC_DIR := target/doc DOC_OPTS := --markdown-no-toc \ --markdown-css stylesheets/normalize.css \ diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md index 6914938a9..58d4a446d 100644 --- a/src/doc/crates-io.md +++ b/src/doc/crates-io.md @@ -1,72 +1,3 @@ - -The string value for each key in this table is a [semver][semver] version -requirement. - -[semver]: https://github.com/steveklabnik/semver#requirements - -**Caret requirements** allow SemVer compatible updates to a specified version. - -`^1.2.3` is an example of a caret requirement. - -When considering “compatible” versions, `0.1` and `0.2` are not considered -compatible, but `1.0` and `1.1` are for example. If no operator is specified, -this is the default requirement (e.g. `1.3` is the same as `^1.3`). - -`0.0.x` is not considered compatible with any other version. Missing minor and -patch versions are desugared to `0` but allow flexibility for that value. - -```notrust -^1.2.3 := >=1.2.3 <2.0.0 -^0.2.3 := >=0.2.3 <0.3.0 -^0.0.3 := >=0.0.3 <0.0.4 -^0.0 := >=0.0.0 <0.1.0 -^0 := >=0.0.0 <1.0.0 -``` - -**Tilde requirements** specify a minimal version with some ability to update. - -`~1.2.3` is an example of a tilde requirement. - -```notrust -~1.2.3 := >=1.2.3 <1.3.0 -~1.2 := >=1.2.0 <1.3.0 -~1 := >=1.0.0 <2.0.0 -``` - -**Wildcard requirements** allow for any version where the wildcard is positioned. - -`*`, `1.*` and `1.2.*` are examples of wildcard requirements. - -```notrust -* := >=0.0.0 -1.* := >=1.0.0 <2.0.0 -1.2.* := >=1.2.0 <1.3.0 -``` - -**Inequality requirements** allow manually specifying a version range or an -exact version to depend on. - -Here are some examples of inequality requirements: - -```notrust ->= 1.2.0 -> 1 -< 2 -= 1.2.3 -``` - -Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, -< 1.5`. - -# Pre-1.0 versions - -While SemVer says that there is no compatibility before 1.0.0, many programmers -treat a `0.x.y` release in the same way as a `1.x.y` release: that is, `y` is -incremented for bugfixes, and `x` is incremented for new features. - -As such, Cargo considers a `0.x.y` and `0.x.z` version, where `z > y`, to be -compatible. - # Publishing crates Ok, now that we’ve got a crate which is using dependencies from crates.io, diff --git a/src/doc/guide.md b/src/doc/guide.md index d3c79c5da..96252483b 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -148,7 +148,9 @@ adds a dependency of the `time` crate: time = "0.1.12" ``` -The version string is a [semver][semver] version requirement. +The version string is a [semver][semver] version requirement. The [specifying +dependencies](specifying-dependencies.html) docs have more information about +the options you have here. [semver]: https://github.com/steveklabnik/semver#requirements @@ -327,74 +329,6 @@ that the argument to `cargo update` is actually a [Package ID Specification](pkgid-spec.html) and `color` is just a short specification. -# Overriding Dependencies - -Sometimes you may want to override one of Cargo’s dependencies. For example, -let’s say you’re working on a project, `conduit-static`, which depends on -the package `conduit`. You find a bug in `conduit`, and you want to write a -patch and be able to test out your patch by using your version of `conduit` -in `conduit-static`. Here’s what `conduit-static`’s `Cargo.toml` looks like: - -```toml -[package] -name = "conduit-static" -version = "0.1.0" -authors = ["Yehuda Katz "] - -[dependencies] -conduit = "0.7" -``` - -You check out a local copy of `conduit`, let’s say in your `~/src` directory: - -```shell -$ cd ~/src -$ git clone https://github.com/conduit-rust/conduit.git -``` - -You’d like to have `conduit-static` use your local version of `conduit`, -rather than the one on crates.io, while you fix the bug. - -Cargo solves this problem by allowing you to have a local configuration -that specifies an **override**. If Cargo finds this configuration when -building your package, it will use the override on your local machine -instead of the source specified in your `Cargo.toml`. - -Cargo looks for a directory named `.cargo` up the directory hierarchy of -your project. If your project is in `/path/to/project/conduit-static`, -it will search for a `.cargo` in: - -* `/path/to/project/conduit-static` -* `/path/to/project` -* `/path/to` -* `/path` -* `/` - -This allows you to specify your overrides in a parent directory that -includes commonly used packages that you work on locally and share them -with all projects. - -To specify overrides, create a `.cargo/config` file in some ancestor of -your project’s directory (common places to put it is in the root of -your code directory or in your home directory). - -Inside that file, put this: - -```toml -paths = ["/path/to/project/conduit"] -``` - -This array should be filled with directories that contain a `Cargo.toml`. In -this instance, we’re just adding `conduit`, so it will be the only one that’s -overridden. This path must be an absolute path. - -Note: using a local configuration to override paths will only work for crates -that have been published to crates.io. You cannot use this feature to tell Cargo -how to find local unpublished crates. - -More information about local configuration can be found in the [configuration -documentation](config.html). - # Tests Cargo can run your tests with the `cargo test` command. Cargo looks for tests @@ -446,40 +380,3 @@ language: rust Please see the [Travis CI Rust documentation](https://docs.travis-ci.com/user/languages/rust/) for more information. - -# Path Dependencies - -Over time our `hello_world` project has grown significantly in size! It’s gotten -to the point that we probably want to split out a separate crate for others to -use. To do this Cargo supports **path dependencies** which are typically -sub-crates that live within one repository. Let’s start off by making a new -crate inside of our `hello_world` project: - -```shell -# inside of hello_world/ -$ cargo new hello_utils -``` - -This will create a new folder `hello_utils` inside of which a `Cargo.toml` and -`src` folder are ready to be configured. In order to tell Cargo about this, open -up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies: - -```toml -[dependencies] -hello_utils = { path = "hello_utils" } -``` - -This tells Cargo that we depend on a crate called `hello_utils` which is found -in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). - -And that’s it! The next `cargo build` will automatically build `hello_utils` and -all of its own dependencies, and others can also start using the crate as well. -However, crates that use dependencies specified with only a path are not -permitted on crates.io. If we wanted to publish our `hello_world` crate, we -would need to publish a version of `hello_utils` to crates.io (or specify a git -repository location) and specify its version in the dependencies line as well: - -```toml -[dependencies] -hello_utils = { path = "hello_utils", version = "0.1.0" } -``` diff --git a/src/doc/header.html b/src/doc/header.html index d42cdba7b..17abf7a89 100644 --- a/src/doc/header.html +++ b/src/doc/header.html @@ -30,6 +30,7 @@